lab components / Text

Formatted Number

Display numerical data

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { FormattedNumber } from "@siteimprove/fancylab";

#Examples

Clearly and consistently display numerical data in a user-friendly format, making it easier for users to interpret and understand key information.

1,234,567.89

CodeHTML output

<FormattedNumber number={1234567.89} locale="en-US" />

#Format

This component supports three display formats:

Number: For standard numerical values (e.g.: counts and metrics).
Percent: For expressing proportions or rates (e.g.: conversion rates, and total increase of page views).
Currency: For financial values, automatically applying the appropriate currency symbol (e.g.: $, €, ¥).

If no format is provided, the number will default to plain numbers. Read more in Understanding Number Formats

123,456,789.00%
USD1,234,567.89
1,234,567.89

CodeHTML output

<FormattedNumber number={1234567.89} locale="en-US" format="percent" />
<br />
<FormattedNumber number={1234567.89} locale="en-US" format="currency" />
<br />
<FormattedNumber number={1234567.89} locale="en-US" format="number" />

The locale parameter controls the number formatting based on regional standards (e.g.: using commas or periods as decimal separators). All standard locale codes from the ECMAScript Internationalization API are supported.

1.234.567,89
1,234,567.89
1.234.567,89

CodeHTML output

<FormattedNumber number={1234567.89} locale="da-DK" format="number" />
<br />
<FormattedNumber number={1234567.89} locale="en-US" format="number" />
<br />
<FormattedNumber number={1234567.89} locale="pt-BR" format="number" />

#Digits

Control the number of digits displayed. The default maximum significant digits is 2.

1.2
1.200
1.25
1.247

CodeHTML output

<FormattedNumber number={1.2} locale="en-US" format="number" digits={3} />
<br />
<FormattedNumber number={1.2} locale="en-US" format="number" digits={3} alwaysShowDigits />
<br />
<FormattedNumber number={1.2468} locale="en-US" format="number" />
<br />
<FormattedNumber number={1.2468} locale="en-US" format="number" digits={3} alwaysShowDigits />

#Currency

When using the currency format, specify the currency code (e.g.: 'USD', 'EUR'). The default is 'USD'.

AUD1,234,567.89

CodeHTML output

<FormattedNumber number={1234567.89} format="currency" currency="AUD" />

#Empty number

If the provided number is empty or invalid, a placeholder (e.g.: '-') will be displayed with an appropriate aria-label for accessibility.

CodeHTML output

<FormattedNumber number={null} />

Displaying large numbers that benefit from formatting for readability.
Showing percentages or currency values.
Presenting numbers in different locales for internationalization.

#Placement

FormattedNumber is typically used in the following places:

Tables: Enhance data clarity and comparisons within table cells. (e.g. Accessibility issues).
Dashboards/ Reports: Highlight key metrics and trends visually. (e.g. Management dashboard).
Key metric listing: Present concise summaries of critical numerical data. (e.g. Key metrics).
Financial Data Displays: Clearly convey monetary amounts and financial metrics. (e.g.Budget analysis).

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your FormattedNumber to existing components for visual consistency.
Options:
- Locale: Adapt number formatting to the user's region (e.g., use commas or periods for decimal separators).
- Precision (Digits): Control the number of decimal places displayed (e.g., show two decimal places). Avoid excessive decimal places unless necessary for precision.
- Currency Code: Specify the two-letter or three-letter currency code (e.g.: 'USD', 'EUR', 'JPY'). Defaults to user's locale if not set.
- Placeholder: Customize the display for empty or invalid numbers (e.g., '-').

#Do not use when

The exact numerical value is critical (e.g., in scientific or technical data where rounding is not acceptable).
Users need the raw, unformatted number for their own calculations.